;;; -*- Mode: TEXT -*-

;;; File:  read-me.text
;;;-------------------------------------------------------------------------;;;
;;;  AUTOCLASS 3.0  Released 5/11/90   contact:  Taylor@pluto.arc.nasa.gov  ;;;
;;;  by P. Cheeseman, J. Stutz., R. Hanson, W. Taylor                       ;;;
;;;  NASA Ames Research Center, MS 244-17, Moffett Field, CA 94035          ;;;
;;;                                                                         ;;;
;;;  Copyright (C) 1990 Research Institute for Advanced Computer Science.   ;;;
;;;  All rights reserved.  The RIACS Software Policy contains specific      ;;;
;;;  terms and conditions on the use of this software, and must be          ;;;
;;;  distributed with any copies.  THIS FILE MAY BE REDISTRIBUTED.  This    ;;;
;;;  copyright and notice must be preserved in all copies made of this file.;;;
;;;-------------------------------------------------------------------------;;;
;;;	revised 5/21/90 for 3.0.1
;;;	revised 6/06/90 for 3.0.2


		GENERAL INFORMATION FOR AUTOCLASS
-------------------------------------------------------------------------------

CONTENTS:
	What Is Autoclass 
        Release History
	Compatibility
	Availability
	FTP Server Organization
	Accessing Autoclass Code
	Building The Autoclass System
	Lisp Environment Dependencies
	Use Of The Autoclass System
	Reporting Your Usage Of Autoclass
	Technical Questions And Feedback On Use Of Autoclass
	Bug Reports

WHAT IS AUTOCLASS:

   AutoClass is an unsupervised Bayesian classification system for
   independent data. It seeks a maximum posterior probability
   classification.

   Inputs consist of a database of attribute vectors and a class model
   defined by a parametric class probability function and corresponding
   parameter priors.  Models are constructed from a specified set of terms
   appropriate to both discrete and real valued attributes.  AutoClass
   attempts to find the set of classes that is maximally probable with
   respect to the data and model.  The output is a set of classes given as
   instances of the model with specific parameters.  There are facilities
   for reporting on the classes, the influence of the attributes on the
   classes, and the probability weighting of the data over the classes.
   
   AutoClass runs in the Common Lisp environment of Symbolics and
   Explorer Lisp machines, and in the Franz and Lucid Lisp implementations 
   on the Sun and similar Unix machines.  For the Symbolics there is an 
   optional user interface for visualizing classification results.


RELEASE HISTORY:

   Version: 3.0	   11 May 90    initial release -
				models: single multinomial,
				single normal (no missing values),
				single normal (with missing values).

   Version: 3.0.1  25 May 90	Ported to Macintosh Allegro CL and NeXT
				Allegro CL.  Minor bug fixes (see 
				autoclass/version-3-0-1.text) and tar
				format available for ftp.

   Version: 3.0.2  06 Jun 90    Minor changes to fix bugs & for Symbolics 
				Genera 8.0.  Checkpointing capability 
				added.  (see autoclass/version-3-0-2.text)

COMPATIBILITY:

   AutoClass was developed on a Symbolics 3650s & XL400s in Common Lisp 
   under Genera 7.2 and 7.4 Ivory.

   It has been compiled and moderately tested in the following
   environments:
	Symbolics -   Genera 8.0
	Sun3 -        Franz Allegro CL 3.1.beta22 [Sun3] 6/7/89
        Sun3 -        Lucid CL 3.0.0.Beta3 18 May 88
        TI Explorer - Release 4.1
	Macintosh -   MACL v. 1.2.2
	NeXT -        Allegro CL v. 3.1

AVAILABILITY:

   AutoClass is available via anonymous FTP or anonymous file copy.
   For those of you without FTP access, send us e-mail with particulars 
   about your situation and requirements and we will try to accommodate you.


FTP SERVER ORGANIZATION:

   All Lisp environments:

      /autoclass/read-me.text
      /autoclass/load-ac.lisp
      /autoclass/version-*.text

      /autoclass/doc/*.*   - AutoClass documentation text files 
      /autoclass/prog/*.*  - AutoClass lisp files
      /autoclass/sample/*.*  - files presenting a sample data base which 
				has been classified by AutoClass

   Symbolics & TI Explorer environments only:

      /autoclass/sys/autoclass.system  - file for AutoClass DEFSYSTEM
      /autoclass/sys/autoclass.translations  - file for AutoClass DEFSYSTEM

   Symbolics environments only:

      /autoclass/sys/autoclass-ui.system - file for AutoClass results user
						interface DEFSYSTEM
      /autoclass/sys/autoclass-ui.translations - file for AutoClass results 
						user interface DEFSYSTEM
      /autoclass/ui/*.*  - Symbolics results user interface lisp files
      /autoclass/ui-library/*.*  - Symbolics results user interface library
					lisp files


ACCESSING AUTOCLASS CODE:

   The FTP server on which AutoClass resides is:

  	riacs.edu	Internet address:  128.102.16.8	

   Not Symbolics & not TI Explorer platforms: Anonymous FTP -

	$ cd autoclass
	$ ftp 128.102.16.8
	ftp> login: anonymous
	ftp> password: anonymous
	ftp> cd pub/autoclass

	either
		ftp> binary
		ftp> get autoclass.tar.Z
	or
		ftp> get *.* *.*
		ftp> lcd doc
		ftp> cd doc
		ftp> mget *.* *.*
		ftp> lcd ../prog
		ftp> cd ../prog
		ftp> mget *.* *.*
		ftp> lcd ../sample
		ftp> cd ../sample
		ftp> mget *.* *.*
	ftp> quit

	If you get the tar file, then you do the following:

		% uncompress autoclass.tar.Z
		% tar xfv autoclass.tar

   Symbolics & TI Explorer platforms: Copy Files with anonymous login -

	Copy File riacs.edu:/pub/autoclass/*.*
					<your autoclass directory>
	Copy File riacs.edu:/pub/autoclass/doc/*.*
					<your autoclass>doc directory>
	Copy File riacs.edu:/pub/autoclass/prog/*.*
					<your autoclass>prog directory>
	Copy File riacs.edu:/pub/autoclass/sample/*.*
					<your autoclass>sample directory>

   TI Explorer platforms only: Copy Files with anonymous login -

	Copy File riacs.edu:/pub/autoclass/sys/autoclass.system
					<your-host>:site;*.*
	Copy File riacs.edu:/pub/autoclass/sys/autoclass.translations
					<your-host>:site;*.*

   Symbolics platforms only: Copy Files with anonymous login -

	Copy File riacs.edu:/pub/autoclass/sys/*.*
					<your-host>:>sys>site>*.*
	Copy File riacs.edu:/pub/autoclass/ui/*.*
					<your autoclass>ui directory>
	Copy File riacs.edu:/pub/autoclass/ui-library/*.*
					<your autoclass>ui-library directory>

	FSEditor: riacs.edu:/pub/autoclass/
        If a namespace entry is made for riacs.edu, then you can use 
	riacs:/pub/autoclass/ rather than  riacs.edu:/pub/autoclass/
        in FSEditor.


BUILDING THE AUTOCLASS SYSTEM:

   Not Symbolics & not TI Explorer platforms:

   	% cd /autoclass 
   	% <invoke Lisp>
   	% (load "load-ac.lisp")
   	% (in-package 'ac)

   	Note: file extension of source files is "lisp". This is the default
   	for "autoclass/prog/sys-dcl.lisp", which builds the system. If you 
        change your copies of the source to your local Lisp dialect file
	extension, change the binding of "files-renamed-p" from nil to t in
   	"autoclass/prog/sys-dcl.lisp".

	Note: If you are using Macintosh Allegro Commom Lisp, then the 
	following forms need to be invoked prior to (load "load-ac.lisp"):
	(setf *default-pathname-defaults* (make-pathname :defaults 
                   "138MB HD: ..... :autoclass:"))
	(setf *compile-definitions* t)
	(def-logical-pathname "autoclass" (make-pathname :defaults 
 		*default-pathname-defaults*))
	(setf *print-length* 3)
	(setf *print-depth* 3)


   TI Explorer platforms:

   	Modify physical pathnames of these files to suit your local 
        environment:

	<your-host>:>sys>site>autoclass.system
	<your-host>:>sys>site>autoclass.translations

   	$ (load ".... >autoclass>load-ac.lisp")
	$ (in-package 'autoclass)

   Symbolics platforms only: (Symbolics results user interface)

   	Modify physical pathnames of these files to suit your local
	environment:

	<your-host>:>sys>site>autoclass.system
	<your-host>:>sys>site>autoclass.translations
 	<your-host>:>sys>site>autoclass-ui.system
	<your-host>:>sys>site>autoclass-ui.translations

   	Change the :increment-version keyword arguments value to t the FIRST
	time you load the AUTOCLASS & AUTOCLASS-UI systems (in file
	LOAD-AC.LISP).
    
   	$ (load ".... >autoclass>load-ac.lisp")
	$ (in-package 'ac)


LISP ENVIRONMENT DEPENDENCIES

   When compiling file the AutoClass system in a non-Symbolics environment, 
   the function DUMP-OBJECT-TO-FILE will be undefined.  This is an
   implementation dependent function for writing binary objects to disk, and 
   as such is only defined for the Symbolics.  You may define your own.  Also 
   PLOT-CLSF will be an undefined function in a non-Symbolics environment.

   The following files, available on the FTP server, are Symbolics
   dependent and can be adapted, if desired, to your Lisp environment:

          search-trace.lisp   intf-graphics.lisp
          intf-plots.lisp     symbolics.lisp

   Note that these two undefined functions will not cause errors while running
   AutoClass in non-Symbolics environments.

   File EXPLORER-4-1-PATCH.LISP is included for users of Release 4.1 of the
   Explorer operating system to correct a bug which we found.


USE OF THE AUTOCLASS SYSTEM:

   To use Autoclass, first you need data (your "db2" file), then you need to
   describe it to AutoClass (your "hd2" & "model" files), and then you
   validity check these files with AUTOCLASS-INPUT-CHECK.  Next, you generate 
   classification results from your data using AUTOCLASS-SEARCH, and finally 
   you produce reports with functions AUTOCLASS-REPORTS-FROM-RESULTS-FILE or
   AUTOCLASS-REPORTS-FROM-CLSF.

   If you are on on a Symbolics, you can use the results user interface to 
   produce the reports and also useful bar-charts & plots.  

   See /autoclass/doc/introduction.text for detailed documentation of the 
   AutoClass system.  The Symbolics results user interface is not documented 
   in the "doc" directory.  Its documentation can be viewed "on-line" by 
   "clicking" on the results user interface Help command.


REPORTING YOUR USAGE OF AUTOCLASS:

   Please send e-mail to taylor@pluto.arc.nasa.gov notifying us when you
   have copied AutoClass.  We will then be able to inform you about
   enhancements, updates and bug fixes.  Also please tell us what type of
   machine, operating system, and Lisp environment you are using.


TECHNICAL QUESTIONS AND FEEDBACK ON USE OF AUTOCLASS:

   We ask that you report (to John Stutz -  stutz@pluto.arc.nasa.gov) 
   any use you make of AutoClass, describing the application and your 
   analysis of the results.  Please feel free to make suggestions about 
   desirable improvements and extensions, and perceived problem areas. 
   We regard such feedback as an essential element of the development 
   process.  


BUG REPORTS:

   Please e-mail bug reports to Will Taylor (taylor@pluto.arc.nasa.gov).

   No guarantees about fixes.  However, we will try to incorporate
   bug fixes into our future development versions of AutoClass.

